REST API: Add finalize endpoint to WP_REST_Attachments_Controller by adamsilverstein · Pull Request #11168 · WordPress/wordpress-develop

adamsilverstein · 2026-03-05T06:52:04Z

Summary

Adds a POST /wp/v2/media/{id}/finalize REST API endpoint to WP_REST_Attachments_Controller
The endpoint triggers the wp_generate_attachment_metadata filter with context 'update' after client-side media processing completes
Ensures server-side plugins (watermarking, CDN sync, custom sizes, etc.) can post-process attachments when client-side processing is active
Only registered when wp_is_client_side_media_processing_enabled() returns true
There is significant usage of this filter by plugins.

Context

When client-side media processing handles image uploads (resizing, thumbnail generation, format conversion), server-side WordPress hooks like wp_generate_attachment_metadata are bypassed. This endpoint is called after all client-side operations (upload, thumbnail generation, sideloads) are complete, re-triggering the filter so plugins continue to work.

Hook usage example

add_filter( 'wp_generate_attachment_metadata', function( $metadata, $attachment_id, $context ) {
  // $context is 'update' when called from the finalize endpoint.
  if ( 'update' === $context ) {
    // Add watermark, sync to CDN, generate custom sizes, etc.
    my_plugin_process_attachment( $attachment_id, $metadata );
  }
  return $metadata;
}, 10, 3 );

Changes

File	Change
`class-wp-rest-attachments-controller.php`	Add `finalize` route registration, `finalize_item_permissions_check()`, and `finalize_item()` methods
`rest-attachments-controller.php` (tests)	Add tests for finalize endpoint (success, auth required, invalid ID)
`rest-schema-setup.php`	Add finalize route to expected routes list
`wp-api-generated.js`	Add finalize route to API fixtures

Test plan

Verify finalize endpoint returns 200 with valid attachment
Verify wp_generate_attachment_metadata filter fires with context 'update'
Verify 401 when not authenticated
Verify 404 for invalid attachment ID
Run full REST API test suite

Commit message

REST API: Add finalize endpoint to `WP_REST_Attachments_Controller`.

Introduce a `POST /wp/v2/media/{id}/finalize` REST API endpoint that re-triggers the `wp_generate_attachment_metadata` filter with context `'update'` after client-side media processing completes. This ensures server-side plugins (watermarking, CDN sync, custom sizes, etc.) can post-process attachments when client-side processing is active.

The endpoint reuses `edit_media_item_permissions_check` for authorization and is only registered when `wp_is_client_side_media_processing_enabled()` returns true.

See https://github.com/WordPress/gutenberg/pull/74913.
See https://github.com/WordPress/gutenberg/issues/74358.

Props adamsilverstein, westonruter, mukesh27, divyeshpatel01.
Fixes #64804.

Add a `POST /wp/v2/media/{id}/finalize` endpoint that triggers the `wp_generate_attachment_metadata` filter after client-side media processing completes. This ensures server-side plugins (e.g., for watermarking, CDN sync, custom sizes) can post-process attachments when client-side processing is active. The endpoint: - Reuses `edit_media_item_permissions_check` for authorization - Re-applies `wp_generate_attachment_metadata` with context 'update' - Updates attachment metadata and returns the updated attachment - Is only registered when client-side media processing is enabled Props adamsilverstein. See #62243. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-03-05T06:53:28Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props adamsilverstein, westonruter, mukesh27.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

github-actions · 2026-03-05T07:03:13Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

tests/phpunit/tests/rest-api/rest-attachments-controller.php

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

mukeshpanchal27 · 2026-03-06T04:56:33Z

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

+					array(
+						'methods'             => WP_REST_Server::CREATABLE,
+						'callback'            => array( $this, 'finalize_item' ),
+						'permission_callback' => array( $this, 'finalize_item_permissions_check' ),


Shell we use edit_media_item_permissions_check directly as the new method class that function and return the value?

I feel like the wrapper approach is pretty standard here? or maybe I'm not understanding your suggestion completely?

Yes but

wordpress-develop/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

Lines 1987 to 1989 in ba6d05d

public function sideload_item_permissions_check( $request ) {

return $this->edit_media_item_permissions_check( $request );

}

use wrapper method.

Can we use single method for both?

Co-authored-by: Weston Ruter <westonruter@gmail.com>

@westonruter

Address remaining code style feedback from @westonruter.

Align equals signs for adjacent variable assignments per WordPress coding standards.

westonruter

Looks good!

mukeshpanchal27

Looks good to me.

Non-blocking feedback https://github.com/WordPress/wordpress-develop/pull/11168/files#r2915787647

westonruter reviewed Mar 6, 2026

View reviewed changes

mukeshpanchal27 reviewed Mar 6, 2026

View reviewed changes

adamsilverstein and others added 3 commits March 10, 2026 11:59

Apply suggestions from @westonruter

672fd49

Co-authored-by: Weston Ruter <westonruter@gmail.com>

Remove extraneous blank lines per review

3a82b96

Address remaining code style feedback from @westonruter.

Fix PHPCS alignment warning in tests

4de3c1d

Align equals signs for adjacent variable assignments per WordPress coding standards.

adamsilverstein requested review from mukeshpanchal27, swissspidy and westonruter March 10, 2026 19:12

westonruter added 2 commits March 10, 2026 17:50

Expand assertions and harden types in tests

a136469

Add assertions that wp_update_attachment_metadata() was actually called

ba6d05d

westonruter approved these changes Mar 11, 2026

View reviewed changes

mukeshpanchal27 approved these changes Mar 11, 2026

View reviewed changes

Merge branch 'trunk' into backport-finalize-endpoint

ec12d75

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

REST API: Add finalize endpoint to WP_REST_Attachments_Controller#11168

REST API: Add finalize endpoint to WP_REST_Attachments_Controller#11168
adamsilverstein wants to merge 7 commits intoWordPress:trunkfrom
adamsilverstein:backport-finalize-endpoint

adamsilverstein commented Mar 5, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 5, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mukeshpanchal27 Mar 6, 2026

Uh oh!

adamsilverstein Mar 10, 2026

Uh oh!

mukeshpanchal27 Mar 11, 2026

Uh oh!

westonruter left a comment

Uh oh!

mukeshpanchal27 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	public function sideload_item_permissions_check( $request ) {
	return $this->edit_media_item_permissions_check( $request );
	}

Conversation

adamsilverstein commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Context

Hook usage example

Changes

Test plan

Related

Commit message

Uh oh!

github-actions bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 5, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mukeshpanchal27 Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

adamsilverstein Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

mukeshpanchal27 Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

mukeshpanchal27 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adamsilverstein commented Mar 5, 2026 •

edited

Loading

github-actions bot commented Mar 5, 2026 •

edited

Loading